---
title: 追踪
description: Learn how to trace your agent runs
---

import { Aside, Code } from '@astrojs/starlight/components';
import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw';
import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw';

Agents SDK 内置了追踪功能，会在一次智能体运行期间收集完整的事件记录：LLM 生成、工具调用、交接、护栏，以及自定义事件。使用 [Traces dashboard](https://platform.openai.com/traces)，你可以在开发与生产中调试、可视化并监控你的工作流。

<Aside type="note">

追踪默认启用。你可以通过两种方式禁用追踪：

1. 通过设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING=1` 全局禁用追踪
2. 将 [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled) 设为 `true` 来仅禁用单次运行的追踪

**_对于使用 OpenAI API 且遵循 Zero Data Retention (ZDR) 政策的组织，追踪不可用。_**

</Aside>

## 导出循环生命周期

在大多数环境中，追踪会按固定间隔自动导出。在浏览器或 Cloudflare Workers 中，此功能默认禁用。追踪在排队过多时仍会被导出，但不会按固定间隔导出。你应在代码生命周期中使用 `getGlobalTraceProvider().forceFlush()` 手动导出追踪。

例如，在 Cloudflare Worker 中，应将代码包裹在 `try/catch/finally` 中，并结合 `waitUntil` 使用强制刷新，以确保在 worker 退出前导出追踪。

<Code
  lang="typescript"
  code={cloudflareWorkers.replace(/\s+\/\/ @ts-expect-error.*$/m, '')}
  meta="{13}"
/>

## Trace 与 Span

- **Traces** 表示一次“工作流”的端到端操作。它们由 Spans 组成。Trace 具有以下属性：
  - `workflow_name`：逻辑上的工作流或应用。例如“代码生成”或“客户服务”。
  - `trace_id`：Trace 的唯一 ID。如果未传入则自动生成。必须满足格式 `trace_<32_alphanumeric>`。
  - `group_id`：可选的分组 ID，用于关联同一会话的多条 Trace。例如可以使用聊天线程 ID。
  - `disabled`：若为 True，将不记录该 Trace。
  - `metadata`：Trace 的可选元数据。
- **Spans** 表示有开始与结束时间的操作。Span 具有：
  - `started_at` 和 `ended_at` 时间戳。
  - `trace_id`，表示其所属的 Trace
  - `parent_id`，指向该 Span 的父 Span（如果有）
  - `span_data`，即关于该 Span 的信息。例如，`AgentSpanData` 包含关于智能体的信息，`GenerationSpanData` 包含关于 LLM 生成的信息等。

## 默认追踪

默认情况下，SDK 会追踪以下内容：

- 整个 `run()` 或 `Runner.run()` 被 `Trace` 包裹
- 每次智能体运行，被 `AgentSpan` 包裹
- LLM 生成被 `GenerationSpan` 包裹
- 函数工具调用各自被 `FunctionSpan` 包裹
- 护栏被 `GuardrailSpan` 包裹
- 交接被 `HandoffSpan` 包裹

默认 Trace 名称为“Agent workflow”。你可以使用 `withTrace` 设置该名称，或通过 [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) 配置名称及其他属性。

此外，你可以设置[自定义追踪处理器](#custom-tracing-processors)，将追踪推送到其他目的地（作为替代或附加目的地）。

### 语音智能体追踪

如果你使用 `RealtimeAgent` 和 `RealtimeSession` 搭配默认的 OpenAI Realtime API，追踪会在 Realtime API 侧自动进行，除非你在 `RealtimeSession` 上通过 `tracingDisabled: true` 或使用环境变量 `OPENAI_AGENTS_DISABLE_TRACING` 禁用。

查看[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)了解更多详情。

## 更高层级的追踪

有时，你可能希望多次调用 `run()` 属于同一个 Trace。可以将整段代码包裹在 `withTrace()` 中实现。

<Code lang="typescript" code={customTraceExample} />

1. 因为两次 `run` 调用被 `withTrace()` 包裹，单次运行将作为整体 Trace 的一部分，而不是创建两个 Trace。

## 创建追踪

你可以使用 [`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 函数创建一个 Trace。或者，使用 `getGlobalTraceProvider().createTrace()` 手动创建新 Trace，并将其传入 `withTrace()`。

当前 Trace 通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行跟踪。这意味着它能自动适配并发。

## 创建 Span

你可以使用各类 `create*Span()` 方法（例如 `createGenerationSpan()`、`createFunctionSpan()` 等）来创建 Span。通常无需手动创建 Span。可使用 [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) 来追踪自定义 Span 信息。

Span 会自动归属于当前 Trace，并嵌套在最近的当前 Span 之下，当前 Span 同样通过 [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 或相应环境的 polyfill 进行跟踪。

## 敏感数据

某些 Span 可能会捕获潜在的敏感数据。

`createGenerationSpan()` 会存储 LLM 生成的输入/输出，而 `createFunctionSpan()` 会存储函数调用的输入/输出。这些可能包含敏感数据，你可以通过 [`RunConfig.traceIncludeSensitiveData
`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) 来禁用捕获这些数据。

## 自定义追踪处理器

追踪的高层架构如下：

- 在初始化时，我们创建一个全局的 [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider)，负责创建 Trace，并可通过 [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) 访问。
- 我们为 `TraceProvider` 配置了一个 [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/)，该处理器会将 Trace/Span 批量发送到 [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/)，该导出器会将 Span 与 Trace 批量导出到 OpenAI 后端。

若要自定义此默认设置，以便将追踪发送到替代或附加后端，或修改导出器行为，你有两种选择：

1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) 允许添加一个“额外的”追踪处理器，它会在 Trace 与 Span 就绪时收到它们。这样你可以在将追踪发送到 OpenAI 后端之外，执行自定义处理。
2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) 允许用你自己的追踪处理器“替换”默认处理器。这意味着除非你包含将数据发送到 OpenAI 后端的 `TracingProcessor`，否则追踪将不会发送到 OpenAI 后端。

## 外部追踪处理器列表

- [AgentOps](https://docs.agentops.ai/v2/usage/typescript-sdk#openai-agents-integration)
- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agents-sdk-js)
